Skip to content

Conversation

@kafitzgerald
Copy link
Contributor

This PR:

  • Adds a central glossary that lives in the Appendix, but can be referenced from anywhere and removes page specific glossaries.
  • Adds several additional abbreviations to the central configuration to fill that out a bit
  • Adds several links to external resources
  • Makes some minor editorial changes to "Why Python?"

Closes #569 and partially addresses #571 (central glossary)

More detailed notes / references:

  • Another option for handling a longer glossary could be to do something like this: https://book.the-turing-way.org/afterword/glossary/
  • MyST glossary, abbreviation, etc. docs here: https://mystmd.org/guide/glossaries-and-terms
  • There are some cases where we'll need to make a call on if we'd like to see an abbreviation, a glossary term, fancy Wikipedia link, external link, or some combination thereof. Personally, I think the Wikipedia links are quite nice for background info / definitions that are a little less central to the Pythia Foundations content, but they do override the abbreviation feature IIRC and not everything has a Wikipedia entry (e.g. NCL). There's probably also a threshold for overuse with those. Anyway, very much open to suggestions / preferences.

@review-notebook-app
Copy link

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@github-actions
Copy link

github-actions bot commented Dec 4, 2025

👋 Thanks for opening this PR! The Cookbook will be automatically built with GitHub Actions. To see the status of your deployment, click below.
🔍 Git commit SHA: 88f567e
✅ Deployment Preview URL: https://ProjectPythia.github.io/pythia-foundations/_preview/582

@kafitzgerald kafitzgerald marked this pull request as ready for review December 4, 2025 02:33
@kafitzgerald kafitzgerald requested a review from a team as a code owner December 4, 2025 02:33
@kafitzgerald kafitzgerald requested review from dopplershift and ktyle and removed request for a team December 4, 2025 02:33
@brian-rose brian-rose self-requested a review December 9, 2025 21:21
Copy link
Member

@brian-rose brian-rose left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This all looks great. I added some small edits and suggestions.

I see this PR as a "first stab" at implementing a comprehensive glossary for the whole book. We can and should open a new issue to track more full implementation of a book-wide glossary. Lots of the glossary terms defined here are used on other pages as well and should be tagged with {term} in the sources as appropriate.

kafitzgerald and others added 6 commits December 9, 2025 19:53
Co-authored-by: Brian Rose <[email protected]>
Co-authored-by: Brian Rose <[email protected]>
Co-authored-by: Brian Rose <[email protected]>
@kafitzgerald
Copy link
Contributor Author

Yeah, I imagine there are quite a few more terms and references to add throughout the book. I was planning to add some w/ the GitHub section updates as well.

For context, the capitalization diffs in the abbreviations were my attempt to differentiate where there were proper nouns. This works too though and is probably easier to maintain.

@brian-rose
Copy link
Member

Yeah, I imagine there are quite a few more terms and references to add throughout the book. I was planning to add some w/ the GitHub section updates as well.

For context, the capitalization diffs in the abbreviations were my attempt to differentiate where there were proper nouns. This works too though and is probably easier to maintain.

I totally appreciate that there are multiple correct editorial styles! For me, the cognitive load is reduced when I stick to the convention of capitalizing all abbreviations, and correspondingly capitalizing all words that contribute to the abbreviation.

Copy link
Member

@brian-rose brian-rose left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One tiny additional edit, sorry!

Co-authored-by: Brian Rose <[email protected]>
Copy link
Member

@brian-rose brian-rose left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work @kafitzgerald!

@brian-rose brian-rose merged commit a8a5fa0 into ProjectPythia:main Dec 10, 2025
3 checks passed
github-actions bot pushed a commit that referenced this pull request Dec 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

EM JOSE Review - Foundations: Why Python?

2 participants